Documentation - ZHLT 2.5.3 Custom Build 1.7

This is a custom build of Zoner's Half-Life Tools, version 2.5.3. Sean (aka "Zoner") is NOT responsible for the tools in this zip. The purpose of this document is to highlight the differences between the generic ZHLT 2.5.3 and this version, and also to serve as a usage manual.

Revised 08/12/`02 Anthony Moore

These improvements are largely the work of many other people. In particular, the following individuals have made significant contributions:

• Skyler "Zipster" York (zipster89134@hotmail.com)
  For work on Maximum Visability Distance and miscellaneous advice
   
• Jussi "hullu" Kivilinna (hullu@unitedadmins.com)
  For work on custom entity shadows, and miscellaneous minor contributions
   
• Laurie Cheers (laurie@valve-erc.com)
  For work on switchable texture based lighting
   
• Adam "Who? Me?" Foster (afoster@compsoc.man.ac.uk)
  For work on sky diffuse and miscellaneous contributions to hlrad

Contents of this file:

• INSTALLATION
• the null texture
• automatic wad detection
• clipnode economy mode
• sky diffuse colour
• custom shadows
• texture wad configuration file
• info_compile_parameters map entity
• info_texlights map entity
• max vis distance

It is recommended that these tools be installed beside or over a copy of the original Zoner's Half-Life Tools, Version 2.5.3, as this zip does not contain all the standard documentation used by a mapper.

Installation is quite simple; all you need to do is extract the entire contents of this zip file to some location on your hard drive. This does not have to be the same location as ZHLT 2.5.3, if you find it convenient to install elsewhere.

Additionally, you need to update the paths your compile controller is using. If you are using Worldcraft/Hammer to compile, this can be done in the Build Programs tab of Worldcraft configuration (which is available under the Tools, Options... menu). If you would rather not do this, then you can always create a new configuration under Expert compile mode and manually specify the paths to the build tools, instead of using the special $csg_exe, $bsp_exe, etc... variables supplied by Worldcraft.

The NULL texture is one that is removed from the map during compilation, so that it won't exist when you play the compiled .bsp file in Half-Life. You should be able to apply it to any entity or world brush within your map.

The main point of this texture is to use it on faces that the player would under normal circumstances never see, so that those faces will not add to the w_poly count and lower the fps (frames per second) rate. (That doesn't mean you can't use it for whatever you want, although.) You can also use the SKY texture for this exact same purpose, although there have been recent debates about whether this is actually beneficial. While it does lower the w_poly count, it apparently also lowers the fps rate, thereby defeating its original purpose.

Note, that:

• NULL textured brushes still block VIS.
• If you have a NULL surface on a HULL brush (ie. a brush acting as the outer layer of your map, sealing it from the void), then in Half-Life the absence of any textured polygon(s) being rendered in that space will cause a Hall of Mirrors effect. This is intended behaviour, and should be accounted for by the mapper.
• NULL textures will still block the player in Half-Life (and anything else that should collide with a wall), even though they are not rendered. This is to preserve the collision detection of the entire brush. If you want to disable this, then just make the brush a func_illusionary.

If you wish to use the NULL texture, make sure that you extract zhlt.wad from this zip to somewhere on your hard drive, and add it to your texture wad configuration in Worldcraft (goto Tools, Options... and click on the Textures tab, then click on Add).

Automatic wad detection is a simple utility that will exclude any wadfiles from the bsp that aren't in use by the map. This gives you, the mapper, the ability to add any assortment of wadfiles you wish, and yet only have those that are actually used by the map included in the .bsp file.

If you wish to enable this feature, simply use the -wadautodetect flag in the hlcsg commandline.

This 'mode' is on by default in hlcsg, and does not require any interaction from the user at all. You can remain blissfully ignorant of this feature if you so wish.

Clipnodes are 'planes' that restrict the player movement. They are placed along the walls and floors of your level, so that they player cannot pass though them. However, like everything else in the Half-Life universe, they are limited, and will max out with compile errors if you end up using too many of them.

In this build of the tools, hlcsg will analyse how the clipnodes are being used in your map. If it thinks that it can get away with not using clipnodes in any particular situation (such as in func_illusionaries which don't need clipnodes), then hlcsg will strip them away from the level. This means that by default, your clipnode counts will be lower than normal. However, it doesn't automatically mean that you will never see another MAX_MAP_CLIPNODES error in your life, it just means it's less likely to happen in the first place.

If you believe that this feature is causing you troubles, than you have the option of turning it off. To do so, simply add the -noclipeconomy flag to the hlcsg commandline.

This is a feature for hlrad written by Jussi Kivilinna (hullu@unitedadmins.com). It allows the mapper to define the transparency and colouring of brush based entities for the purposes of the shadows that those brushes cast.

To use this feature, the brush based entity must have its opaque flag set in zhlt_lightflags (if you do not have an .fgd that has this option for all brush based entities, you should download the latest one from the Valve-ERC). This opaque brush entity will now cast normal shadows, just like any other brush.

To customise this shadow, take smart-edit off in Worldcraft, and add a keyvalue called zhlt_customshadow. The value of this keyvalue should represent how opaque the brush based entity should be treated in hlrad, on a scale from 1.0 to 0.0 (where 1.0 is fully opaque, casting no shadow, and 0.0 being fully transparent, casting a full shadow).

Additionally, colour may be added to this shadow. Instead of defining one value, define 3, representing the RGB values of the shadow (on the same scale). For example, if I wanted a brush to cast a red shadow (for say, a red stain glass window effect), i would use the value 0.5 0.0 0.0, or similar.

If you specify any value above 1.0, hlrad will cast additional light (useful for and effect that may require luminecent shadows, or another effect that may require a particular shape of light).

By default, none of these will take effect on bounced light; for this to occur, you must specify the -customshadowwithbounce parameter.
However;

• Usage of -customshadowwithbounce with the vismatrix and sparse settings on hlrad will cause significant slowdowns; it is recommended that you also use -nomatrix with this option.
• The -customshadowwithbounce parameter will only work for greyscale shadows.

Release Information
The texture wad configuration file, called wad.cfg should be extracted to the same directory as the compile tools, or your Half-Life directory.

Whats the purpose of this feature?
Say, you map for 3 mods: Counter-Strike, TFC, and normal Half-Life Single Player. All three of these mods use different wads. Say you wanted to work on your Counter-Strike map one day, and TFC the next: because Worldcraft does not store which wad files are in use for each game configuration, you would need to go into Worldcraft texture configuration, Add/Remove wad files from the list, and Restart Worldcraft.

The idealistic solution to this would be to make it so that Worldcraft stores which wad files are in use for any given game configuration, but that's not as easy as it would first appear. autolycus of the Valve-ERC states that "This is one of the most requested things, so yes, we know about it. I've requested the feature several times. You can be assured, Mr. Speyrer knows that this would be a handy thing.".

The solution
So, for the mean time, I have devised up this method to overcome the hassle of restarting Worldcraft. In the wad.cfg file, you can explicitly define what wads you want written into the .bsp file, regardless of what happens to be in Worldcraft, for any given game configuration. So, now, hlcsg will ignore the wads that you have configured in Worldcraft, and instead only write in the ones you specify.

The specific syntax for the file is the following:

configuration_name
{
c:\path\to\wad\wad1.wad
c:\path\to\wad\wad2.wad
include c:\path\to\wad\wad3.wad
}

Where:

• configuration_name is some sort of descriptive word. Examples: valve, cs, tfc etc...
• c:\path\to\wad\wadn.wad is the full path to a texture wad file. if you are unsure as to what this should be, take a look at the paths in the Textures tab in Worldcraft configuration.
• If a wad is prefixed by include, that wad will be automatically wadincluded into the .bsp file.
• There is no limit to the number of configurations, or the number of wads you can have per configuration.

Lets take an example. Say i wanted to create a configuration called 'my_wads'. It has 3 standard wadfiles in it: 'halflife.wad', 'liquids.wad' and 'xeno.wad', all of which can be found in the valve directory, because they all came with Half-Life. It also has a custom wad created by me called 'mywad.wad', which I want to compile into the .bsp file, which also happens to be in the valve directory. My configuration might look something like this:

my_wads
{
C:\Sierra\Half-Life\valve\halflife.wad
C:\Sierra\Half-Life\valve\liquids.wad
C:\Sierra\Half-Life\valve\xeno.wad
include C:\Sierra\Half-Life\valve\mywad.wad
}

Now, when i run hlcsg.exe when i compile my map, i put -wadconfig my_wads in the command line.

If you really don't understand the wad.cfg file syntax, then don't worry. You don't have to use it. However, it does come with some example configurations already in it; just open it in notepad and see if you can get the hang of it, because it can be quite handy.

@PointClass size(-8 -8 0, 8 8 32) = info_compile_parameters : "Compile Options" 
[ 
    hlcsg(choices) : "HLCSG" : 1 =
    [
        1 : "Normal"
        2 : "Onlyents"
        0 : "Off"
    ]
    hlbsp(choices) : "HLBSP" : 1 =
    [
        0 : "Off" 
        1 : "Normal"
        2 : "Leakonly"
    ]
    hlvis(choices) : "HLVIS" : 2 = 
    [ 
        0 : "Off"
        1 : "Fast"
        2 : "Normal" 
        3 : "Full"
    ]
    hlrad(choices) : "HLRAD" : 1 =
    [
        0 : "Off"
        1 : "Normal"
        2 : "Extra"
    ]
    texdata(string) : "Texture Data Memory (in KB)" : "4096" 
    estimate(choices) : "Estimate Compile Times?" : 0 = 
    [ 
        0: "Yes" 
        1: "No" 
    ] 
    bounce(integer) : "Number of radiosity bounces" : 0 
    ambient(string) : "Ambient world light (0.0 to 1.0, R G B)" : "0 0 0" 
    smooth(integer) : "Smoothing threshold (in degrees)" : 0 
    dscale(integer) : "Direct Lighting Scale" : 1 
    chop(integer) : "Chop Size" : 64 
    texchop(integer) : "Texture Light Chop Size" : 32 
    hullfile(string) : "Custom Hullfile" 
    priority(choices) : "Priority Level" : 0 =
    [
        0 : "Normal"
        1 : "High"
        -1 : "Low"
    ]
    wadautodetect(choices) : "Wad Auto Detect" : 0 =
    [
        0 : "Off"
        1 : "On"
    ]
    wadconfig(string) : "Custom Wad Configuration" : ""
    verbose(choices) : "Verbose compile messages" : 0 =
    [
        0 : "Off"
        1 : "On"
    ]
    noclipeconomy(choices) : "Strip Uneeded Clipnodes?" : 1 = 
    [
        1 : "Yes"
        0 : "No"
    ]
    nocliphull(choices) : "Generate clipping hulls" : 0 =
    [
        0 : "Yes"
        1 : "No"
    ]
    noskyclip(choices) : "No Sky Clip" : 0 =
    [
        1 : "On"
        0 : "Off"
    ]
    sparse(choices) : "Vismatrix Method" : 2 =
    [
        0 : "No Vismatrix"
        1 : "Sparse Vismatrix"
        2 : "Normal"
    ]
    circus(choices) : "Circus RAD lighting" : 0 =
    [
        0 : "Off"
        1 : "On"
    ]
]        

The info_texlights entity can act as a replacement for a lights.rad file, in that it simply resides within the map as a point based entity. The usefulness of this is that each map can have its own unique ambient lighting applied to it, and those settings will travel with the map and not affect any other maps.

Usage of the entity is much like that of the multimanager. To add an entry, take smart-edit off in Worldcraft and add key value pairs in manually; the key should contain the name of the texture to apply lighting to, and the value a set of numbers representing the red green blue lumionsity(brightness) of the texture, just as you would in the lights.rad file.

Notes: The presence of this file will not override the lights.rad, both the values specified in this entity and the lights.rad file will be used by hlrad. Thanks goes out to Laurie Cheers from the Spirit of Half-Life mod for the idea behind this entity.

If your .fgd does not contain an info_texlights entity, then you can add this line of code to your .fgd yourself:

@PointClass color(255 128 0) = info_texlights : "Texture Light Config" []

	style(choices) : "Texlight style" : 0 =
	[
		0 : "Normal"
		-3: "Grouped"
		10: "Fluorescent flicker"
		2 : "Slow, strong pulse"
		11: "Slow pulse, noblack"
		5 : "Gentle pulse"
		1 : "Flicker A"
		6 : "Flicker B"
		3 : "Candle A"
		7 : "Candle B"
		8 : "Candle C"
		4 : "Fast strobe"
		9 : "Slow strobe"
		12: "Underwater"
	]